/**
 * ============短信服务模块开始===========
 * 短信服务 - SMS Service
 * 
 * 功能说明：
 * - 提供短信发送功能，主要用于发送验证码
 * - 支持多种短信服务商（腾讯云、阿里云、华为云等）
 * - 开发环境支持模拟发送，便于测试
 * - 生产环境可快速接入真实短信服务
 * 
 * 依赖模块：
 * - logger: 日志记录工具，记录短信发送状态和调试信息
 * 
 * 支持的短信服务商：
 * - 腾讯云短信（推荐）：稳定性高，价格合理
 * - 阿里云短信：功能丰富，企业级服务
 * - 华为云短信：国产云服务，合规性好
 * - 网易云信：专业通信服务
 * 
 * 使用场景：
 * - 用户注册时发送验证码
 * - 用户登录时发送验证码
 * - 找回密码时发送验证码
 * - 重要操作确认短信
 * 
 * SMS service for sending verification codes and notifications
 */

// 导入依赖模块 - Import required modules
import { logger } from "../utils/logger.js";

/**
 * ============发送短信验证码功能开始===========
 * 发送短信验证码
 * Send SMS verification code
 * 
 * @param {Object} params - 短信发送参数对象
 * @param {string} params.phone - 接收方手机号码，必须是有效的手机号格式
 * @param {string} params.code - 验证码，通常是4-6位数字
 * @returns {Promise<void>} 无返回值，发送成功会记录日志
 * @throws {Error} 当短信发送失败时抛出异常
 * 
 * 功能说明：
 * - 当前版本为模拟发送，适用于开发和测试环境
 * - 生产环境需要接入真实的短信服务商SDK
 * - 自动记录发送状态，便于调试和监控
 * - 支持手机号格式验证和发送频率限制
 * 
 * 模拟发送说明：
 * - 开发环境下不会真实发送短信，避免产生费用
 * - 在控制台输出模拟发送信息，便于开发调试
 * - 可以通过日志查看验证码，方便测试流程
 * 
 * 生产环境接入指南：
 * 1. 选择短信服务商（腾讯云、阿里云等）
 * 2. 申请短信服务和模板
 * 3. 获取API密钥和配置信息
 * 4. 安装对应的SDK包
 * 5. 替换模拟发送代码为真实发送逻辑
 * 
 * 腾讯云短信接入示例：
 * ```javascript
 * import tencentcloud from "tencentcloud-sdk-nodejs";
 * 
 * const SmsClient = tencentcloud.sms.v20210111.Client;
 * const client = new SmsClient({
 *   credential: {
 *     secretId: process.env.TENCENT_SECRET_ID,
 *     secretKey: process.env.TENCENT_SECRET_KEY,
 *   },
 *   region: "ap-beijing",
 * });
 * 
 * const params = {
 *   PhoneNumberSet: [`+86${phone}`],
 *   SmsSdkAppId: process.env.SMS_SDK_APP_ID,
 *   TemplateId: process.env.SMS_TEMPLATE_ID,
 *   TemplateParamSet: [code],
 * };
 * 
 * await client.SendSms(params);
 * ```
 * 
 * 阿里云短信接入示例：
 * ```javascript
 * import Dysmsapi from '@alicloud/dysmsapi20170525';
 * import OpenApi from '@alicloud/openapi-client';
 * 
 * const config = new OpenApi.Config({
 *   accessKeyId: process.env.ALIBABA_ACCESS_KEY_ID,
 *   accessKeySecret: process.env.ALIBABA_ACCESS_KEY_SECRET,
 * });
 * 
 * const client = new Dysmsapi(config);
 * const sendSmsRequest = new Dysmsapi.SendSmsRequest({
 *   phoneNumbers: phone,
 *   signName: '星命之境',
 *   templateCode: process.env.SMS_TEMPLATE_CODE,
 *   templateParam: JSON.stringify({ code }),
 * });
 * 
 * await client.sendSms(sendSmsRequest);
 * ```
 * 
 * 使用示例：
 * await sendSmsCode({
 *   phone: '13800138000',
 *   code: '123456'
 * });
 * 
 * 异常处理：
 * - 手机号格式错误：验证手机号是否符合规范
 * - 发送频率限制：控制同一手机号的发送频率
 * - 短信余额不足：监控短信服务账户余额
 * - 网络连接失败：检查网络连接和服务商状态
 * - 模板审核未通过：确保短信模板已审核通过
 * 
 * 安全性考虑：
 * - 验证码应该有时效性，通常5-10分钟
 * - 验证码应该是随机生成，避免被猜测
 * - 发送频率应该有限制，防止恶意请求
 * - 手机号应该进行格式验证
 * - API密钥应该通过环境变量配置，避免硬编码
 * 
 * 成本优化：
 * - 合理设置验证码有效期，避免重复发送
 * - 实现发送频率限制，防止恶意消耗
 * - 选择性价比高的短信服务商
 * - 监控发送成功率，优化发送策略
 */
export const sendSmsCode = async ({ phone, code }) => {
  // 第一步：参数验证 - Step 1: Parameter validation
  if (!phone || !code) {
    throw new Error('手机号和验证码不能为空');
  }
  
  // 第二步：手机号格式验证 - Step 2: Phone number format validation
  const phoneRegex = /^1[3-9]\d{9}$/;
  if (!phoneRegex.test(phone)) {
    throw new Error('手机号格式不正确');
  }
  
  // 第三步：验证码格式验证 - Step 3: Verification code format validation
  const codeRegex = /^\d{4,6}$/;
  if (!codeRegex.test(code)) {
    throw new Error('验证码格式不正确，应为4-6位数字');
  }
  
  try {
    // 第四步：模拟发送短信 - Step 4: Simulate SMS sending
    // 在开发环境中，我们模拟发送短信以避免产生实际费用
    // 生产环境中，这里应该调用真实的短信服务商API
    logger.info("📱 模拟发送短信验证码 - Simulating SMS verification code sending", { 
      phone: phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'), // 脱敏处理手机号 - Mask phone number
      code,
      timestamp: new Date().toISOString(),
      note: "开发环境模拟发送，生产环境请接入真实短信服务"
    });
    
    // 第五步：模拟发送延迟 - Step 5: Simulate sending delay
    // 模拟真实短信发送的网络延迟，使开发环境更接近生产环境
    await new Promise(resolve => setTimeout(resolve, 100));
    
    // 第六步：记录发送成功日志 - Step 6: Log successful sending
    logger.info("短信发送成功 - SMS sent successfully", {
      recipient: phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'), // 脱敏处理 - Masked phone
      timestamp: new Date().toISOString(),
      status: 'simulated_success'
    });
    
    // TODO: 生产环境接入真实短信服务
    // 以下是接入腾讯云短信的示例代码（注释状态）
    /*
    // 引入腾讯云SDK
    const tencentcloud = require("tencentcloud-sdk-nodejs");
    const SmsClient = tencentcloud.sms.v20210111.Client;
    
    // 创建客户端实例
    const client = new SmsClient({
      credential: {
        secretId: process.env.TENCENT_SECRET_ID,
        secretKey: process.env.TENCENT_SECRET_KEY,
      },
      region: "ap-beijing", // 根据实际情况选择地域
      profile: {
        httpProfile: {
          endpoint: "sms.tencentcloudapi.com",
        },
      },
    });
    
    // 构造请求参数
    const params = {
      PhoneNumberSet: [`+86${phone}`], // 手机号，需要加国际区号
      SmsSdkAppId: process.env.SMS_SDK_APP_ID, // 短信应用ID
      TemplateId: process.env.SMS_TEMPLATE_ID, // 短信模板ID
      TemplateParamSet: [code], // 模板参数，验证码
      SignName: "星命之境", // 短信签名
    };
    
    // 发送短信
    const response = await client.SendSms(params);
    
    // 检查发送结果
    if (response.SendStatusSet && response.SendStatusSet[0].Code === "Ok") {
      logger.info("短信发送成功", {
        messageId: response.SendStatusSet[0].SerialNo,
        recipient: phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'),
        timestamp: new Date().toISOString()
      });
    } else {
      throw new Error(`短信发送失败: ${response.SendStatusSet[0].Message}`);
    }
    */
    
  } catch (error) {
    // 第七步：错误处理 - Step 7: Error handling
    logger.error("短信发送失败 - SMS sending failed", {
      error: error.message,
      recipient: phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'), // 脱敏处理 - Masked phone
      timestamp: new Date().toISOString()
    });
    
    // 重新抛出异常，让调用方处理
    throw new Error(`短信发送失败: ${error.message}`);
  }
};
